<h1 id="swxdocumentation-versionalpha0.1g">SWX Documentation - version Alpha 0.1g</h1>

<h2 id="whatisswx">What is SWX?</h2>

<p>SWX stands for SWF Data Exchange Format. It&#8217;s a new way of working with data in Flash that uses simple SWF files to exchange data. SWX is the natural, native way to get data into Flash: You loadMovie() your data!</p>

<p>A quick example follows.</p>

<h2 id="front-endflash">Front-end (Flash)</h2>

<pre><code>import org.swxformat.*;

// dataHolder is a movie clip on Stage.
dataHolder.serviceClass = "Simple";
dataHolder.method = "echoData";
dataHolder.arguments = ['arguments', 'to', 'send'];

// Serialize the arguments data in PHON format.
Prepare.forPhp(dataHolder);

// Call the gateway.
dataHolder.loadMovie("http://a.com/path/to/swx.php", "POST");

// A very simple check for returned result.
function onEnterFrame()
{
    debug_txt.text = "Data: " + dataHolder.result;
}
</code></pre>

<p>That&#8217;s all there is to it! SWX will create an instance of the Simple class in PHP and call its echoData() method, passing the arguments specified in the arguments array. It will then return the results in a variable called result wrapped in a SWX SWF file. (In this case, the echoData() method simply sends back the data object you sent it.)</p>

<p>Since the SWX SWF file you receive contains your data in native SWF bytecode, you don&#8217;t have to worry about deserializing the data once you received it: You can just use it! </p>

<p>Another advantage is that you can use getBytesLoaded() and getBytesTotal() to show a determinate preloader for your data! The SWF Data Exchange Format (SWX) is a very limited subset of the SWF specification &#8212; it&#8217;s a SWF that only contains data. </p>

<p>Before sending data from Flash to the back-end, you must serialize the data you&#8217;re sending in PHON format. You do this by asking SWX to prepare it for PHP using Prepare.forPhp(dataHolder);</p>

<p>PHON is a new data format. It stands for PHP Object Notation. It is based on JSON (JavaScript Object Notation) by Douglas Crockford. Basically, it is a native PHP data structure. PHON is a very limited subset of PHP (see the section on security for a discussion of the security considerations of using PHON &#8212; in a nutshell, it&#8217;s secure!)</p>

<h2 id="back-endphp">Back-end (PHP)</h2>

<p>When you request data from PHP, you get a SWX SWF with the data inside it in native SWF bytecode (there is no deserialization involved.) The moment your data SWF has loaded, the data is available for you to access without delay. </p>

<p>So what does the back-end look like? Like everything else in SWX, it&#8217;s very simple. </p>

<p>You simply create classes with public methods that return data and you place these classes in the /services folder. You can then call these public methods from Flash by doing a loadMovie() on the SWX gateway. You specify the <em>serviceClass</em>, <em>method</em> and an <em>arguments</em> array to pass to the method as properties in the movie clip you&#8217;re loading the data into (see the Flash section, above).</p>

<p>Here&#8217;s the Simple.php example:</p>

<pre><code>class Simple
{
     // Echo the passed data 
    public function echoData($data)
    {
        return $data;
    }   
}
</code></pre>

<p>That&#8217;s it! The SWX gateway (swx.php) handles everything else: The security check to make sure that a valid PHON object is passed, security checks to make sure that only public methods of classes in the /services folder can be used, the instantiation of the class and, of course, the serialization of the data returned by the class into SWF format using the SWX SWF Compiler. You don&#8217;t have to worry about any of these things. As far as you&#8217;re concerned, you&#8217;re calling a method on a PHP class and receiving its return value as a native data structure inside a SWF.</p>

<p>The current alpha version of SWX only supports PHP but there&#8217;s no reason for other programming languages and application servers to not be supported. Porting SWX to other languages is not a huge task as the most complicated bit, the generated SWF bytecode, is made up of chunks of constants that will not change. I expect that we will see Python, Ruby, Java and .Net versions of SWX contributed by members of the community in coming days. </p>

<h1 id="debugging:usingtheswxanalyzer">Debugging: Using the SWX Analyzer</h1>

<p>You can see the data that is returned from an SWX call using the SWX Analyzer if you turn debug mode on.</p>

<p>To turn debug mode on, set a property called debug in your data holder movie clip. For example: </p>

<p>dataHolder.debug = true;</p>

<p>(You don&#8217;t necessarily need to set it to true. As long as the debug property exists, the returned SWX SWF will contain debug code.)</p>

<p>Once you&#8217;ve set debug mode on, start the SWX Analyzer and test your Flash project. You will see the returned data appear in the SWX Analyzer.</p>

<p>SWX Analyzer is a Flex application. (An apollo version will be available soon.) </p>

<h1 id="thephondataformat">The PHON Data Format</h1>

<p>PHON is a new format that stands for PHP Object Notation. It is based on JSON (JavaScript Object Notation) by Douglas Crockford. Basically, it is a native PHP data structure. PHON is a very limited subset of PHP.</p>

<p>A PHON object is a string.</p>

<p>A PHON object must have an array as its root element. (This restriction may be eased in future iterations.) The array may be empty. Thus the smallest valid PHON object is simply &#8220;array()&#8221;.</p>

<p>A PHON object may contain string data values. String data values inside a PHON object must be quoted using single quotes. Double quotes are not allowed.</p>

<p>A PHON object may only contain the following elements outside of quotes:</p>

<ul>
<li>array (regular and associative)</li>
<li>numbers (integer and floating point)</li>
<li>boolean values (true and false)</li>
<li>a dot to specify the decimal point for floating point numbers</li>
<li>=> assignment operator for associative arrays</li>
<li>commas for separating array items</li>
</ul>

<p>A valid PHON object must not contain any other elements and should not have a trailing statement terminator (semicolon).</p>

<p>PHON does not dictate the contents of string data values and SWX does not sanitize the contents of string data values in any way. This may change in the future, in line with SWX&#8217;s philosophy of making things as simple as possible for the developer. We may do string sanitization to provide a basic level of MySQL injection protection, for example. Traditionally, this has been the responsibility of the application developer, but there&#8217;s nothing traditional about SWX! :) </p>

<p>Is PHON secure?</p>

<p>Yes. PHON is a very limited subset of PHP and there are very strict rules on what a valid PHON object can contain. Because PHON objects from untrusted clients are evaled on the server, we must be sure that arbitrary code does not execute. SWX uses strict regular expression matching to ensure that only valid PHON objects are executed on the server. </p>

<h1 id="theswxphilosophy">The SWX Philosophy</h1>

<p>SWX is designed to provide Flash developers with a simple and enjoyable experience when building data-driven applications in Flash. The key words here are simple, enjoyable and experience. </p>

<p>Simplicity: SWX is as simple as possible but no simpler. If something can be made simpler without sacrificing essential core functionality, I&#8217;ll make it simpler. </p>

<p>Enjoyable: Because life should be fun. The SWX tools aim to put a smile on your face, do the heavy lifting, provide a seamless experience and be aesthetically pleasing so you&#8217;ll be inspired todo the same in your applications.</p>

<p>Experience: These core tenets apply to the whole experience of SWX, not just the API or codebase. That includes the web site, documentation and tools. The focus is to make it as easy as possible for you to get up and running with SWX from the first moment you visit the <a href="http://swxformat.org">SWX web site</a>.</p>

<h1 id="compatibility">Compatibility</h1>

<p>SWX is compatible with Flash 7+ (ActionScript 1 and ActionScript 2). I haven&#8217;t tested it with FlashLite 2 but It Should Just Work (tm).</p>

<p>The SWX SWF files are based on the bytecode generated for Flash 6 r65 but they don’t currently work when loaded into a SWF that’s published for the Flash 6 player. I will look into this if I have time but Flash 6 support is currently not a priority — unless someone can give me a compelling reason why it should be, of course! </p>

<p>On the server-side, it works with PHP 4 and 5 (only tested with PHP 4.4.2 and 5.1.4).</p>

<p>SWX only supports ActionScript 1 and ActionScript 2 at the moment. You can use SWX with Flex 2 and AS3 by creating a debug SWX SWF and making use of the LocalConnection. More native support may be added in the future. For an example of how to do this, see the Flex 2 source code for the SWX Analyzer.</p>

<h1 id="howdoesitwork">How does it work?</h1>

<p>Here&#8217;s a technical overview if you&#8217;re interested in learning more about how SWX works and was created. </p>

<p>At the core of SWX is a SWF assembler (SwfCompiler.php) I wrote that creates SWX SWF files from PHP data structures and a SWX gateway (swx.php) that acts as a front controller for data requests. I wrote the SWX SWF assembler by disassembling SWF files generated by the Flash compiler using Flasm, Swfdump and a hex editor (i.e., discovery through observation). The bytecode for the generated SWX SWF files is compatible with but differs slightly from that produced by the Flash compiler. This may or may not change in the future as optimizations are implemented. </p>

<p>The SWX SWF format is a very limited subset of the SWF format. An SWX SWF is a 1x1 SWF at 1FPS that has one frame and only contains data.</p>

<p>On the client side, any data to be sent to the back-end must be serialized using the native object notation for the back-end. Currently, there is support for PHP with PHON (PHP Object Notation).</p>

<h1 id="howdoyoupronounceswx">How do you pronounce SWX?</h1>

<p>I go back and forth between calling it S-W-X and &#8220;swix&#8221;. You can use both :)</p>

<h1 id="whosthecutelittleguythen">Who&#8217;s the cute little guy, then?</h1>

<p>If you&#8217;re asking about the SWX mascot/logo, his name&#8217;s Datum! He lives in a SWF shell :)</p>

<h1 id="knownissuesandlimitations">Known issues and limitations</h1>

<p>SWX is currently in very early alpha form: It may creak, break, or throw its toys. This is to be expected and I highly encourage you to test it out and report any issues you&#8217;re having to me so I can fix them. It will be invaluable to me if you can send me the ActionScript and/or PHP data structures that are causing the issues. </p>

<p>There are several known issues and limitation with this alpha release. </p>

<p>The main one is performance: SWX is currently not optimized in any way. </p>

<p>This means that neither the PHP code nor the SWF bytecode is optimized and that SWX is currently slower in serializing its data than other alternative technologies (Remoting, XML, etc.) </p>

<p>I expect that we will see a huge improvement in this area once both the PHP code and SWF bytecode is optimized. However, this will come later as my priority right now is making SWX as robust as possible before undertaking any sort of optimization work that will make the codebase harder to work with in the future. </p>

<p>If you have any optimization hints and tips, please do send them to me but realize that I will not implement them until later in the development cycle.</p>

<p>SWX is for you to play with, provide feedback on and create cool little apps with. Please do <em>not</em> use this alpha version in mission-critical applications.</p>

<p>See the roadmap to see which issues I&#8217;m aware of and will be implementing in the coming days. </p>

<h1 id="roadmap">Roadmap</h1>

<p>SWX is in heavy development. Here&#8217;s a current but incomplete roadmap that will be updated regularly:</p>

<h2 id="showstoppers">Showstoppers</h2>

<ul>
<li>None.</li>
</ul>

<h2 id="testing">Testing</h2>

<ul>
<li>Unit test coverage has dropped dramatically since I started creating bytecode that is slightly different from what the Flash compiler produces. Create tests for all data types, edge cases, etc. based on currently functional bytecode generated by the SWX Compiler.</li>
</ul>

<p>I also need your help in testing SWX. Please download SWX and play with it. If it breaks, let me know and send me the data structures that broke it.</p>

<ul>
<li>Test with FlashLite 2/2.1.</li>
<li>Test with Flash 7 &amp; 8 to make sure there aren&#8217;t any version-specific issues. </li>
<li>Test on Nintendo Wii with Opera browser. </li>
</ul>

<h2 id="discovery">Discovery</h2>

<ul>
<li>Would the Laszlo folks be interested in creating a port for Laszlo?</li>
</ul>

<h2 id="majorfunctionalitytoaddecrs">Major functionality to add (ECRs)</h2>

<ul>
<li>PHP: Add utility class that uses CURL to consume REST/JSON services  * allowDomain option in SWX SWF files for cross-domain use. Thanks for reminding me of this, Justin &#8212; you rock! (Note: This is not a priority for me currently. The primary use case for SWX is to expose data on the server to your Flash client. You can consume services on the server. But this will be useful for deployments with several subdomains, etc., so it will be added.)</li>
<li>See deployment &amp; distribution, below.</li>
</ul>

<h2 id="deploymentdistribution">Deployment &amp; distribution</h2>

<ul>
<li>Create integrated MAMP installer</li>
<li>Add Amfphp to the distribution</li>
</ul>

<h2 id="documentationtutorialsexamples">Documentation, tutorials &amp; examples</h2>

<ul>
<li>Documentation, tutorials and examples for the website</li>
<li>Create OSFlash site for SWX</li>
<li>Create HTML landing page for SWX users in source tree just like we have a page for SWX development. Integrate the analyzer into that. </li>
<li>Create examples that use SWX alongside AMFPHP: eg. (a) APIs that support Remoting, XML, JSON and SWX &#8212; demonstrating how to use a single business object to output in all these various formats. (b) Using the REST/JSON class to consume services and expose them as SWX (creating mashups easily.)</li>
<li>Create FlashLite example.</li>
<li>Create Nintendo Wii example.</li>
</ul>

<h2 id="analyzer">Analyzer</h2>

<ul>
<li>Create Apollo version with OS X and Windows bundles.</li>
<li>Add documentation and help.</li>
</ul>

<h2 id="optimization">Optimization</h2>

<ul>
<li>Optimize PHP code</li>
<li>Optimize SWF bytecode</li>
<li>Create native C extension for use in deployment</li>
</ul>

<h2 id="ports">Ports</h2>

<ul>
<li>SWX Python (with PYON) - Port project lead: N/A. Status: Not started. </li>
<li>SWX Ruby (with RON)- Port project lead: N/A. Status: Not started. </li>
<li>SWX Java (with JON)- Port project lead: N/A. Status: Not started. </li>
<li>SWX .Net (with CON)- Port project lead: N/A. Status: Not started. </li>
</ul>

<p>Let me know if you&#8217;re interested in porting SWX to any of the above technologies (or any others.) PYON (Python object notation), RON (Ruby Object Notation), JON (Java Object Notation), and CON (C# Object Notation) are simply implementations of PHON (PHP Object Notation) in these other languages. </p>

<h1 id="swxcredits">SWX Credits</h1>

<p>Conceived, developed and maintained by <a href="http://aralbalkan.com">Aral Balkan</a>. </p>

<p>Hosted on <a href="http://osflash.org">OSFlash</a>; the home of the Open Source Flash community.</p>

<h1 id="swxacknowledgments">SWX Acknowledgments</h1>

<p>To everyone whom I&#8217;ve learned from, thank you!</p>

<p><a href="http://www.nowrap.de/">Igor Kogan</a> and Wang Zhen for <a href="http://flasm.sourceforge.net/">Flasm</a> and <a href="http://www.quiss.org/">Matthias Kramm</a> for Swfdump (part of <a href="">Swftools</a>). My life would have been astronomically more difficult without these two excellent SWF disassemblers. </p>

<p><a href="http://JSON.org">Douglas Crockford</a> for thinking different. PHON is based on JSON.</p>

<p>Tony Million for making <a href="http://www.suavetech.com/0xed/0xed.html">0xED</a>, a hex editor for OS X that was extremely useful for viewing SWF bytecode.</p>

<p><a href="http://www.5etdemi.com/blog/">Patrick Mineault</a> for creating AMFPHP. I hope SWX and AMFPHP become bosom buddies! </p>

<p><a href="http://apple.com">Apple</a>, for making my amazing MacBook Pro and for giving me OS X. After 22 years of increasing amounts of frustration with DOS and Windows, I love using a computer again. My Mac has definitely made me a better developer!</p>

<p><a href="http://twitter.com">Twitter</a> for keeping my connected and the cafe at my local Borders, where a portion of SWX was written, for giving me a change of scene in the mornings.</p>

<p>The lovely folks at MAMP for making it child&#8217;s play to get a development server up and running on OS X and the gang at ApacheFriends for doing the same for Windows and Linux users. SWX will include custom distributions of both of these packages that also contain SWX.</p>

<p>Macromates for making <a href="http://macromates.com/">Textmate</a>. It&#8217;s my best friend :)</p>

<p><a href="http://www.lastcraft.com/simple_test.php">SimpleTest</a>, <a href="http://asunit.org/">AsUnit</a>, and <a href="http://subversion.tigris.org/">SVN</a>  for giving me piece of mind.</p>

<p>My friends at <a href="http://adobe.com">Adobe</a> for making Flash, Flex and Apollo possible. </p>

<p>Our wonderful <a href="http://osflash.org">OSFlash</a> community sharing your knowledge openly and for giving me inspiration and hope every day. You guys rock!</p>

<p>Brighton, my fellow Brightonians, and our lovely little geek community here in the UK for your inspiration and friendship. </p>

<p>A special thank-you to Niqui, Pete, Dave, Paul, Justin, Danny, Jeremy, John and Serge, for your feedback, support and encouragement.</p>

<p>And last, but definitely not least, a big thank-you to my parents for your lifelong support and for always encouraging me regardless of what I&#8217;m doing. There&#8217;s a bit of you in everything I do. </p>

<h1 id="swxlicensing">SWX Licensing</h1>

<p>SWX is open source software, released under the [MIT license]
(http://www.opensource.org/licenses/mit-license.php). The SWX MAMP distribution and certain other components have different licenses. Please refer to the respective license documents for details.</p>

<p><a rel="license"
href="http://creativecommons.org/licenses/by-sa/2.0/uk/">
<img alt="Creative Commons License" style="border-width:0"
src="http://i.creativecommons.org/l/by-sa/2.0/uk/88x31.png" /></a>
<br />The <span xmlns:dc="http://purl.org/dc/elements/1.1/"
href="http://purl.org/dc/dcmitype/Text" rel="dc:type">SWX documentation and web site content</span> is
licensed under a 
<a rel="license"
href="http://creativecommons.org/licenses/by-sa/2.0/uk/">Creative
Commons Attribution-Share Alike 2.0 UK: England &amp; Wales
License</a>.</p>

<p>SWX, swxformat.org, Datum (the SWX logo) are trademarks of Aral Balkan. </p>

<p>SWX, the SWX web site and any other related products are offered as-is without any warranties or guarantees of any kind as per the Terms and Conditions. </p>

<p>SWX is not affiliated with Adobe. Adobe and Flash are registered trademarks of Adobe, Inc. All other trademarks and copyrights belong to their respective owners. </p>

<p>The full text of the SWX license follows:</p>

<p>Copyright &#xA9; 2007 <a href="http://aralbalkan.com">Aral Balkan</a>. </p>

<p>Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the &#8220;Software&#8221;), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:</p>

<p>The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.</p>

<p>THE SOFTWARE IS PROVIDED &#8220;AS IS&#8221;, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.</p>
